home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / gui / precog2_1.lha / Precognition2_1 / include / Intuition_utils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-11-14  |  11.6 KB  |  373 lines
  1. #ifndef INTUITION_UTILS_H
  2. #define INTUITION_UTILS_H
  3.  
  4. #include <exec/types.h>
  5. #include <intuition/intuition.h>
  6. #include <intuition/screens.h>
  7. #include <graphics/gfx.h>        /* for type 'Point' */
  8.  
  9. #include "parms.h"
  10.  
  11. /* ~~~~~~~~~~~~~~~~~~~ Intuition_Utils ~~~~~~~~~~~~~~~~~~~~~~~~~~
  12.  
  13.    This is a collection of handy Intuition-related utilities.
  14.    These do not depend on any of the Precognition types or routines
  15.    and can be reused outside of the Precognition environment.
  16.  
  17.    Note: the strange comment headers are for use with a tool
  18.    which automatically builds man pages from the comments.
  19. */
  20.  
  21.  
  22. /*F:is_Workbench_v2*
  23.  
  24. ----------------------------------------------------
  25.  
  26.          is_Workbench_v2
  27.  
  28. ----------------------------------------------------
  29.  
  30. Name:    is_Workbench_v2 - returns TRUE if running AmigaDOS version >= 2.0
  31. Syntax:  | result = is_Workbench_v2();
  32.          | BOOL result;
  33. Author:  Lee R. Willis
  34. */
  35.  
  36. BOOL is_Workbench_v2 __PARMS(( void ));
  37.  
  38.  
  39.  
  40. /*F:is_Workbench_v2_1*
  41.  
  42. ----------------------------------------------------
  43.  
  44.          is_Workbench_v2_1
  45.  
  46. ----------------------------------------------------
  47.  
  48. Name:    is_Workbench_v2_1 - returns TRUE if running AmigaDOS version >= 2.1
  49. Syntax:  | result = is_Workbench_v2_1();
  50.          | BOOL result;
  51. Author:  Edward D. Berger, Lee R. Willis
  52. */
  53.  
  54. BOOL is_Workbench_v2_1 __PARMS(( void ));
  55.  
  56.  
  57.  
  58. /*F:is_Workbench_v3*
  59.  
  60. ----------------------------------------------------
  61.  
  62.          is_Workbench_v3
  63.  
  64. ----------------------------------------------------
  65.  
  66. Name:    is_Workbench_v3 - returns TRUE if running AmigaDOS version >= 3.0
  67. Syntax:  | result = is_Workbench_v3();
  68.          | BOOL result;
  69. Author:  Edward D. Berger, Lee R. Willis
  70. */
  71.  
  72. BOOL is_Workbench_v3 __PARMS(( void ));
  73.  
  74.  
  75.  
  76. /*F:is_Workbench_v3_1*
  77.  
  78. ----------------------------------------------------
  79.  
  80.          is_Workbench_v3_1
  81.  
  82. ----------------------------------------------------
  83.  
  84. Name:    is_Workbench_v3_1 - returns TRUE if running AmigaDOS version >= 3.1
  85. Syntax:  | result = is_Workbench_v3_1();
  86.          | BOOL result;
  87. Author:  Edward D. Berger, Lee R. Willis
  88. */
  89.  
  90. BOOL is_Workbench_v3_1 __PARMS(( void ));
  91.  
  92.  
  93.  
  94. /*F:GadgetRelativeCoords*
  95.  
  96. ----------------------------------------------------
  97.  
  98.                GadgetRelativeCoords
  99.  
  100. ----------------------------------------------------
  101.  
  102. Name:          GadgetRelativeCoords - translates mouse coords relative to gadget
  103. Syntax:        | GadgetRelativeCoords( gadget, event, point );
  104.                | struct Gadget *gadget;
  105.                | struct IntuiMessage *event;
  106.                | Point *point;
  107. Description:   'GadgetRelativeCoords()' is a function which translates
  108.                the MouseX and MouseY fields of an IntuiMessage to be
  109.                relative the supplied gadget.  (MouseX and MouseY are
  110.                returned by Intuition relative to the window, not the
  111.                gadget.)
  112.  
  113. Notes:         AmigaDOS version 2.0 intuition.library has
  114.                a built-in function to do this.
  115.  
  116. Author:  Lee R. Willis
  117. */
  118.  
  119. void GadgetRelativeCoords __PARMS(( struct Gadget       *gadget,
  120.                            struct IntuiMessage *event,
  121.                            Point               *point ));
  122.  
  123.  
  124.  
  125. /*F:SetWaitPointer*
  126.  
  127. -------------------------------------------------
  128.  
  129.                SetWaitPointer
  130.  
  131. -------------------------------------------------
  132.  
  133. Name:          SetWaitPointer - sets the pointer to the standard 2.0 'clock'.
  134. Syntax:        | SetWaitPointer( w );
  135.                | struct Window *w;
  136. Description:   'SetWaitPointer()' sets the mouse pointer to look like
  137.                the standard Workbench 2.0 wait pointer (a clock).
  138. Author:        Lee R. Willis
  139. */
  140.  
  141. void SetWaitPointer __PARMS(( struct Window *w ));
  142.  
  143.  
  144. /*F:WaitForMessage
  145.  
  146. ----------------------------------------------------
  147.  
  148.                WaitForMessage
  149.  
  150. ----------------------------------------------------
  151.  
  152. Name:          WaitForMessage - waits for and returns an IntuiMessage.
  153. Syntax:        | imgs = WaitForMessage( mport );
  154.                | struct IntuiMessage *imsg;
  155.                | struct MsgPort *mport;
  156.  
  157. Description:   Most Intuition event loops start out with the
  158.                following statements to get a message:
  159.                |
  160.                | for(;;)
  161.                | {
  162.                |    msg = (struct IntuiMessage*) GetMsg( window->UserPort );
  163.                |    if (msg == NULL)
  164.                |    {
  165.                |       WaitPort(window->UserPort);
  166.                |       continue;
  167.                |    }
  168.                |
  169.                This grabs a message from the port, and if no message is there,
  170.                does a Wait, and tries again.  I always found this code
  171.                somewhat confusing and very ugly.  So I wrote WaitForMessage
  172.                to hide it.
  173.  
  174.                'WaitForMessage()' does not return until it finds a message,
  175.                so the above code can be replaced by:
  176.                |
  177.                | for(;;)
  178.                | {
  179.                |    msg = WaitForMessage( window->UserPort );
  180.                |
  181.  
  182. Author:        Lee R. Willis
  183. */
  184.  
  185.  
  186. struct IntuiMessage *WaitForMessage __PARMS(( struct MsgPort *mport ));
  187.  
  188.  
  189. /*F:OpenWindowWithSharedUserPort*
  190.  
  191. ------------------------------------------------------------
  192.  
  193.                OpenWindowWithSharedUserPort
  194.  
  195. ------------------------------------------------------------
  196.  
  197. Name:          OpenWindowWithSharedUserPort - opens a window with a shared port.
  198. Syntax:        | window = OpenWindowWithSharedPort( nw, port );
  199.                | struct Window    *window;
  200.                | struct NewWindow *nw;
  201.                | struct MsgPort   *port;
  202.  
  203. Description:   To handle multiple windows within the one application, the
  204.                best method (usually) is to have all the windows share the
  205.                same UserPort.  This way, one can still do a 'WaitPort()' or
  206.                'WaitForMessage()'.  (Otherwise one has to mess with signal
  207.                bits.)
  208.  
  209.                In order to force a window to have a specific UserPort, one
  210.                must first create the port (using 'CreatePort()'), and then
  211.                there is a sequence of steps involved in opening the window.
  212.                (This is described in the 1.3 RKM Libraries and Devices manual
  213.                on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER
  214.                PORT")
  215.  
  216.                'OpenWindowWithSharedPort()' does all the steps after the
  217.                creation of the MsgPort.   All you do is pass in the NewWindow
  218.                structure and the message port, and
  219.                'OpenWindowWithSharedUserPort' will open the window and do
  220.                the UserPort setup.
  221.  
  222. Note:          Windows opened with this function must be closed using
  223.                'CloseWindowWithSharedUserPort()', NOT 'CloseWindow()'!
  224.  
  225. See Also:      CloseWindowWithSharedUserPort
  226. Author:        Lee R. Willis
  227. */
  228.  
  229. struct Window *OpenWindowWithSharedUserPort __PARMS(( struct NewWindow *nw,
  230.                                              struct MsgPort   *shared ));
  231.  
  232.  
  233. /*F:CloseWindowWithSharedUserPort*
  234.  
  235. ------------------------------------------------------------
  236.  
  237.                CloseWindowWithSharedUserPort
  238.  
  239. ------------------------------------------------------------
  240.  
  241. Name:          CloseWindowWithSharedUserPort - closes a window with a shared port.
  242. Syntax:        | CloseWindowWithSharedPort( w );
  243.                | struct Window *w;
  244. Description:   To handle multiple windows within the one application, the
  245.                best method (usually) is to have all the windows share the
  246.                same UserPort.  This way, one still to a 'WaitPort()' or
  247.                'WaitForMessage()'.  (Otherwise one has to mess with signal
  248.                bits.)
  249.  
  250.                Closing such a window requires some care, as Intuition normally
  251.                deallocates the UserPort for such a window on closing, and
  252.                since the port is shared, other windows are still using it!
  253.                (This is described in the 1.3 RKM Libraries and Devices manual
  254.                on page 167 "SETTING UP YOUR OWN IDCMP MONITOR TASK AND USER
  255.                PORT")
  256.  
  257.                'CloseWindowWithSharedUserPort()' does all this for you.
  258.  
  259. See Also:      OpenWindowWithSharedUserPort
  260. Author:        Lee R. Willis
  261. */
  262.  
  263. void CloseWindowWithSharedUserPort __PARMS(( struct Window *w ));
  264.    /* Taken from 1.3 RKM:L&D, page 171 'CloseWindowSafely' */
  265.  
  266.  
  267. /*F:WindowSanityCheck
  268.  
  269. ------------------------------------------------------------
  270.  
  271.                WindowSanityCheck
  272.  
  273. ------------------------------------------------------------
  274.  
  275. Name:          WindowSanityCheck - checks the size and location of a window
  276. Syntax:        | ok = WindowSanityCheck( screen, location, size );
  277.                | BOOL ok;
  278.                | struct Screen *screen;
  279.                | Point *location;
  280.                | Point *size;
  281.  
  282. Description:   WindowSanityCheck checks a proposed new size and location
  283.                for a window to make sure those dimensions will not exceed
  284.                the screen size.
  285.  
  286.                WindowSanityCheck returns TRUE if the proposed dimensions
  287.                are ok, and FALSE if the window dimensions must be changed.
  288.                If the return is FALSE, the values of 'location' and 'size'
  289.                are returned modified to the closest legal dimensions.
  290.  
  291. Author:        Lee R. Willis
  292. */
  293.  
  294. BOOL WindowSanityCheck __PARMS(( struct Screen *screen,
  295.                         Point         *location,
  296.                         Point         *size ));
  297.  
  298.  
  299. /*F:SmartOpenScreen
  300.  
  301. -----------------------------------------------------------------
  302.  
  303.                SmartOpenScreen
  304.  
  305. -----------------------------------------------------------------
  306.  
  307. Name:          SmartOpenScreen - Opens a screen in WB2.0 style if appropriate.
  308. Syntax:        | screen = SmartOpenScreen( newscreen );
  309.                | struct Screen *screen;
  310.                | struct NewScreen *newscreen;
  311.  
  312. Description:   SmartOpenScreen opens a screen.  If you're running under
  313.                1.3, it just calls OpenScreen.  If you're running under
  314.                2.0, it does the minimal processing required so that windows
  315.                on the screen get the 3D look.
  316.  
  317. Author:        Lee R Willis
  318. */
  319.  
  320. struct Screen *SmartOpenScreen __PARMS(( struct NewScreen *newscreen ));
  321.  
  322.  
  323. /*F:SmartOpenScreen
  324.  
  325. -----------------------------------------------------------------
  326.  
  327.                SmartOpenWindow
  328.  
  329. -----------------------------------------------------------------
  330.  
  331. Name:          SmartOpenScreen - Opens a screen in WB3.0 style if appropriate.
  332. Syntax:        | window = SmartOpenWindow( newwindow );
  333.                | struct Window *window;
  334.                | struct NewWindow *newwindow;
  335.  
  336. Description:   SmartOpenWindow opens a window.  If you're running under
  337.                1.3, it just calls OpenWindow.  If you're running under
  338.                3.0, it does the minimal processing required so that menus
  339.                under 3.0 Amiga OS get the new black text on white background
  340.                look. This also requires a change to the menu code as well.
  341.  
  342.  
  343. Author:        Edward D. Berger
  344. */
  345.  
  346. struct Window *SmartOpenWindow __PARMS(( struct NewWindow *newwindow ));
  347.  
  348.  
  349. /*F:RemapImage
  350.  
  351. ------------------------------------------------------------------
  352.  
  353.       RemapImage
  354.  
  355. ------------------------------------------------------------------
  356.  
  357. Name:          RemapImage() - flips planes 1&2 of an image
  358. Syntax:        | RemapImage( image );
  359.                | struct Image *image;
  360.  
  361. Description:   RemapImage exchanges the first two planes of an image data
  362.                structure.  This converts from the look of Workbench 1.2/3
  363.                to the look of Workbench 2.0.
  364.  
  365.                It ASSUMES that there are two planes (i.e. don't feed
  366.                it PlanePick'ed images.)
  367.  
  368. Author:        Lee R Willis
  369. */
  370. void RemapImage __PARMS(( struct Image *image ));
  371.  
  372. #endif
  373.